home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / pascal / oop55.zip / OOPDEMOS.DOC < prev    next >
Text File  |  1989-05-02  |  24KB  |  678 lines
  1.  
  2.                  Turbo Pascal 5.5 Documentation
  3.               Object-Oriented Programming Examples
  4.  
  5. This file documents the Turbo Pascal 5.5 Object-Oriented
  6. Programming (OOP) examples. There are over 12,000 lines of
  7. examples contained in the OOPDEMOS.ARC file on the disk labeled
  8. OOP/DEMOS/BGI/DOC. (If you have a hard disk and run the INSTALL
  9. program to install Turbo Pascal on your system, it will place the
  10. OOP examples in C:\TP by default.)
  11.  
  12.  
  13. TABLE OF CONTENTS
  14. -----------------
  15.  
  16.  1.  OBJECTS.PAS - Basic object types unit
  17.  
  18.  2.  ODEMO.PAS - An example that uses streams and lists
  19.  
  20.  3.  FORMS.PAS - Implements a form entry and edit object
  21.  
  22.  4.  SLIDERS.PAS - Implements a slider field
  23.  
  24.  5.  FDEMO.PAS - A simple forms editor example
  25.  
  26.  6.  CARDS.PAS - Implements a card file object
  27.  
  28.  7.  CARDFILE.PAS - A simple card filer applciation
  29.  
  30.  8.  CARDGEN.PAS - Card filer forms generator
  31.  
  32.  9.  TCALC.PAS - See TCALC.DOC
  33.  
  34. 10.  Examples from the Object-Oriented Programming Guide
  35.  
  36.      Four examples are included from the OOP Guide for your
  37.      convenience:
  38.  
  39.        POINTS   PAS  - From P-20 of the OOP Guide
  40.        FIGURES  PAS  - From P-42 of the OOP Guide
  41.        FIGDEMO  PAS  - From P-47 of the OOP Guide
  42.        LISTDEMO PAS  - From P-57 of the OOP Guide
  43.  
  44.     These examples are fully documented in Chapter 1 of the OOP
  45.     Guide.
  46.  
  47.  
  48. OBJECTS.PAS - BASIC OBJECT TYPES UNIT
  49. -------------------------------------
  50.  
  51. The Objects unit implements two basic object types: a Stream and
  52. a List. The Stream type is the object-oriented counterpart of a
  53. Pascal file. Turbo Pascal 5.5 does not allow "file of object"
  54. types, but streams may be used to implement the same
  55. functionality, and much more as the example programs show. The
  56. List type implements a singly-linked list of objects, each of
  57. which must be derived from the Node type.
  58.  
  59.  
  60. The Base type
  61. -------------
  62.  
  63. Base is an abstract object type, and serves only as an ultimate
  64. ancestor for other object types. Objects of type Base are never
  65. instantiated. Object types derived from Base are guaranteed to
  66. have a destructor called Done. In addition, the VMT field of
  67. descendants of Base will always be the first field in the
  68. descendant, which is a prerequisite of types registered with a
  69. stream.
  70.  
  71. Unless overridden, the Done destructor in Base does nothing
  72. except to dispose the instance when called via the extended
  73. syntax of the Dispose standard procedure.
  74.  
  75.  
  76. The Stream type
  77. ---------------
  78.  
  79. Much like an untyped file, a stream implements a number of basic
  80. I/O capabilities, such as opening, closing, reading, writing, and
  81. seeking. What sets a stream apart from an untyped file is its
  82. ability to polymorphically read and write objects. This is best
  83. demonstrated through an example.
  84.  
  85. Assume that you have three object types, Circle, Rectangle, and
  86. Triangle, each of which are derived from an ancestor type Shape.
  87. In order to read and write such objects to disk you would need a
  88. FILE OF Shape that allows reading and writing of objects of type
  89. Shape as well as descendants of Shape. For a number of reasons,
  90. ordinary Pascal FILE types cannot achieve this. First, objects of
  91. type Circle, Rectangle, and Triangle are most likely not of the
  92. same size, since each will add a varying number of fields to the
  93. basic Shape type. Thus, it would be impossible to determine the
  94. proper record size for a FILE OF Shape. Second, a FILE OF Shape
  95. would need to store additional type information for each object
  96. in the file so that when reading the file, the application can
  97. "know" the types of the objects it is reading.
  98.  
  99. The Stream type provides the solution to this problem: By
  100. defining a Store and Load method in an object type, and by
  101. registering that type with a stream, the stream can perform
  102. polymorphic I/O through its Put and Get methods. The FORMS.PAS
  103. unit and the CARDFILE.PAS program provide good examples on how to
  104. use streams.
  105.  
  106. The Stream type is the ancestor of all other streams. It defines
  107. the basic properties of a stream, but most of its methods are
  108. purely abstract and meant to be overridden in descendant types.
  109.  
  110.  
  111. FIELDS
  112.  
  113. TypeCount       Number of types registered with the stream.
  114.  
  115. TypeList        Pointer to array of VMT offsets of registered types.
  116.  
  117. ProcList        Pointer to array of Store and Load method pointers.
  118.  
  119. Status          Stream status. When Status is non-zero, an error
  120.                 has occurred on the stream, and all subsequent
  121.                 I/O is suspended. The Status field is the
  122.                 equivalent of the IOResult standard function,
  123.                 except that you have to manually clear Status to
  124.                 re-enable I/O operations.
  125.  
  126.  
  127. CONSTRUCTORS AND DESTRUCTORS
  128.  
  129. constructor Init;
  130.  
  131.   Initializes the stream by allocating TypeList and ProcList, and
  132.   calling RegisterTypes to register the types known by the
  133.   stream.
  134.  
  135. destructor Done; virtual;
  136.  
  137.   Disposes TypeList and ProcList.
  138.  
  139.  
  140. BASIC I/O METHODS
  141.  
  142. procedure Read(var Buf; Count: Word); virtual;
  143.  
  144.   Reads Count bytes from the stream into Buf. In case of error,
  145.   Buf is filled with zeros. This method must be overridden.
  146.  
  147. procedure Write(var Buf; Count: Word); virtual;
  148.  
  149.   Writes Count bytes from Buf onto the stream. This method must
  150.   be overridden.
  151.  
  152. procedure Flush; virtual;
  153.  
  154.   Flushes the stream's I/O buffer, if any. This method does
  155.   nothing unless overridden.
  156.  
  157. procedure Truncate; virtual;
  158.  
  159.   Truncates the stream at the current position, i.e. makes the
  160.   current position the end of the stream. This method must be
  161.   overridden.
  162.  
  163. function GetPos: Longint; virtual;
  164.  
  165.   Returns the current position of the stream, or -1 in case of
  166.   error.
  167.  
  168. procedure SetPos(Pos: Longint; Mode: Byte); virtual;
  169.  
  170.   Sets the current position of the stream to a new position that
  171.   is Pos bytes from the stream location given by Mode. Valid Mode
  172.   values are given by the constants PosAbs, PosCur, and PosEnd,
  173.   which represent the stream's beginning, current position, and
  174.   end. This method must be overridden.
  175.  
  176. function GetSize: Longint;
  177.  
  178.   Returns the current size of a stream. Calls SetPos and GetPos
  179.   to find the resulting value. This method should not be
  180.   overridden.
  181.  
  182. procedure Seek(Pos: Longint);
  183.  
  184.   Seeks to the specified position. Corresponds to a call to
  185.   SetPos with a Mode value of PosAbs. This method should not be
  186.   overridden.
  187.  
  188.  
  189. TYPE REGISTRATION METHODS
  190.  
  191. procedure RegisterTypes; virtual;
  192.  
  193.   Registers all types that should be known to the stream. To
  194.   register types with a stream you must override this method and
  195.   call the Register method for each type. Within an overridden
  196.   RegisterTypes, always first call the inherited RegisterTypes to
  197.   register any types required by the ancestor. A type need only
  198.   be registered if instances of the type are read and written
  199.   using the Get and Put methods. Unless overridden, this method
  200.   does nothing.
  201.  
  202. procedure Register(TypePtr, StorePtr, LoadPtr: Pointer);
  203.  
  204.   Registers a type with the stream. This method must only be used
  205.   within a RegisterTypes method. The format of a method call is:
  206.  
  207.     Register(TypeOf(AType), @AType.Store, @AType.Load);
  208.  
  209.   where AType is an object type derived from the Base object type
  210.   (i.e. an object type whose ultimate ancestor is Base). AType
  211.   must define Store and a methods with the following headers:
  212.  
  213.     procedure Store(var S: Stream);
  214.     constructor Load(var S: Stream);
  215.  
  216.   The Store method must write a binary representation of the
  217.   object onto the stream S (using S.Write), and the Load
  218.   constructor must read such a binary representation back from
  219.   the stream S (using S.Read).
  220.  
  221.  
  222. POLYMORPHIC I/O METHODS
  223.  
  224. procedure Put(P: BasePtr);
  225.  
  226.   Writes the specified object to the stream. The type of the
  227.   object must have been registered with the stream (using an
  228.   overridden RegisterTypes method). Put writes a 16-bit object
  229.   type identifier number onto the stream and then calls the
  230.   object's Store method, which writes a binary copy of the
  231.   object. The 16-bit object type identifier corresponds to the
  232.   index of the